<html>
<head>
<title>QStarDict documentation</title>
<link rel="stylesheet" type="text/css" href="styles/style.css">
</head>
<body>

<div id="wrap">
<h1>QStarDict documentation</h1>

<p>
QStarDict is a dictionary application. It allows the user to install
Kiwix and StarDict dictionaries and look up words from these dictionaries.
</p>

<p>This guide is aimed to assist you in using QStarDict.</p>

<h2>Contents</h2>
<ul>
<li><a href="#starting-qstardict">Starting QStarDict</a></li>
<li><a href="#running-in-background">Running in background</a></li>
<li><a href="#starting-with-system">Starting with system</a></li>
<li><a href="#installing-kiwix-dictionaries">Installing Kiwix dictionaries</a></li>
<li><a href="#installing-stardict-dictionaries">Installing StarDict dictionaries</a></li>
<li><a href="#looking-up-words">Looking up words</a></li>
<li><a href="#popup-window">Popup window</a></li>
</ul>

<a href="#starting-qstardict" name="starting-qstardict"><h2>Starting QStarDict</h2></a>
<p>It is possible to start QStarDict either through the menu of the desktop
environment in the "Education" section or using the command line by typing the
command</p>

<p><code>
qstardict
</code></p>

<a href="#running-in-background" name="running-in-background"><h2>Running in background</h2></a>

<p>When QStarDict is started, it can be either in normal mode, when
the main window is shown as here:

<img src="images/main-window-intro.png" width="100%">

or it can be started in background mode.
</p>

<p>
When QStarDict runs in background mode, it is displayed in the notification area:
</p>

<p align="center"><img src="images/notification-area.png"></p>

<p>
The purpose of the background mode is to make it possible for QStarDict to scan
selection in other applications and to show the popup window with dictionary
articles.
See the section on <a href="#popup-window">popup window</a>
for more details.
</p>

<p>
In order to make QStarDict able to run in background, the corresponding setting
should be set on:

<img src="images/settings-run-in-background.png" width="100%">

By default it is on.
</p>

<p>
QStarDict remembers whether it was in normal or background mode on exit, and
on a subsequent start it restores the state of being in background.
</p>

<p>
If you want QStarDict to be started in background, use the
<code>--background</code> command line option by starting QStarDict as
</p><p>
<code>
qstardict --background
</code>
</p>

<a href="#starting-with-system" name="starting-with-system"><h2>Starting with system</h2></a>
<p>
It is possible to set up starting of QStarDict with system in common desktop
environments. In order to enable starting of QStarDict with system, use the
corresponding setting:
</p>

<p align="center"><img src="images/settings-start-with-system.png" width="100%"></p>

<p>
By default starting with system is off.
</p>

<a href="#installing-kiwix-dictionaries" name="installing-kiwix-dictionaries">
<h2>Installing Kiwix dictionaries</h2></a>

<p>
<a href="https://kiwix.org/en/">Kiwix</a> is a project which goal is to create offline versions of websites. The most
prominent of these websites for using with QStarDict is <a href="https://www.wiktionary.org/">Wiktionary</a>.
</p>

<p>
In order to download offline versions of Wiktionary for languages you are interested in, visit
<a href="https://download.kiwix.org/zim/wiktionary/">Kiwix ZIM download page</a> and select the
"nopic" version of Wiktionary for the language you are interested in.
</p>

<p>Note that the language specified in the filename is the target language, not a
source language. Each language contains articles for words in all source languages,
in the target language. For instance, if you want to look up words in Russian
translated to English, you need to use the file with "en_all" language code.
</p>

<p>Examples of filenames:</p>
<ul>
<li>"wiktionary_en_all_nopic_2023-07.zim" is a dictionary in English for all languages</li>
<li>"wiktionary_ru_all_nopic_2023-09.zim" is a dictionary in Russian for all languages</li>
</ul>

<p>
Let us suppose that you have downloaded a file "wiktionary_en_all_nopic_2023-07.zim" to "~/Downloads" directory.
</p>

<p>
It can be installed from the "Dictionaries" tab of the Settings Dialog, which can be opened using
"Settings"&nbsp;→&nbsp;"Configure QStarDict" menu in the main window:

<img src="images/settings-dictionaries-add.png" width="100%">

</p><p>
In order to install a dictionary, press the "Add Dictionary" button, which is marked on the screenshot.
</p>

<p>
Doing it would result in opening a file dialog:
</p>

<img src="images/file-dialog-kiwix.png" width="100%">

<p>
In the file dialog, select "Kiwix ZIM files" filter (marked on the screenshot) and then pick
the ZIM file you want to add.
</p>

<p>When the file is selected, an add dictionary dialog would appear:</p>

<img src="images/add-dialog-kiwix.png">

<p>
It would prompt you to move the dictionary file to a QStarDict's directory.
</p>

<p>
It is also possible to not move, but create a symbolink link to the dictionary
file. In order to do it, select "Symlink" in the combobox in the add dialog.
</p>

<p>
After importing the dictionary, it would appear at the top of the list of
dictionaries in the settings dialog:
</p>

<img src="images/settings-dictionaries-dict-kiwix.png" width="100%">

<p>
After pressing OK the added dictionary will be enabled and it will be possible to
<a href="#looking-up-words">look up words</a> from it.
</p>

<a href="#installing-stardict-dictionaries" name="installing-stardict-dictionaries"><h2>Installing StarDict dictionaries</h2></a>

<p>
QStarDict supports StarDict 2.x and StarDict 3.x dictionaries.
</p>

<p>
A StarDict dictionary consists of three files:
</p>

<ul>
<li>".ifo", a file containing metadata about the dictionary
<li>".idx", an index file of the dictionary
<li>".dict.dz", a file containing dictionary articles
</ul>

<p>
It is possible to install a StarDict dictionary to QStarDict by opening the "Dictionaries" tab in the Settings Dialog,
which can be opened using "Settings"&nbsp;→&nbsp;"Configure QStarDict" menu in the main window:

<img src="images/settings-dictionaries-add.png" width="100%">

In order to install a dictionary file to QStarDict, press the "Add Dictionary" button, which is marked on the
screenshot.
</p>

<p>
Doing it would result in opening a file dialog:
</p>

<img src="images/file-dialog-stardict.png" width="100%">

<p>
In the file dialog, select "StarDict IFO files" filter (marked on the screenshot) and then pick the ".ifo" file of the dictionary you want to add.
</p>

<p>Note that the <code>.idx</code> and <code>.dict.dz</code> files must be in the same directory as the
<code>.ifo</code> file in order to allow the dictionary to be successfully imported.
</p>

<p>
After importing the dictionary, it would appear at the top of the list of
dictionaries in the settings dialog:
</p>

<img src="images/settings-dictionaries-dict-stardict.png" width="100%">

<p>
After pressing OK the added dictionary will be enabled and it will be possible to
<a href="#looking-up-words">look up words</a> from it.
</p>

<a href="#looking-up-words" name="looking-up-words"><h2>Looking up words</h2></a>

<p>
It is possible to look up words in the main window of QStarDict. The words to be
looked up can be typed into the text input. By default, the words are searched
as soon as they are typed, but this behaviour can be turned off in the General tab
of the settings dialog.
</p>

<a href="#popup-window" name="popup-window"><h2>Popup window</h2></a>

<p>
A popup window is a window that can be shown near words selected by mouse. Its
behaviour can be configured in the "Popup window" tab of the settings dialog.
</p>

</div>
</body>
</html>
